Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

IXFileFinderQueryAndUpdate

Adopted By:	IXFileFinder

Declared In:	indexing/IXFileFinder.h

Protocol Description

The IXFileFinderQueryAndUpdate protocol defines much of the real functionality of the IXFileFinder class.  All of the querying and index building methods are in this protocol.  There are also a few methods for getting miscellaneous information about the IXFileFinder.

Sending a Query or an Update Request

The methods for performing a query or updating the file finder's indexÐperformQuery:atPath:forSender:, and updateIndex:atPath:forSender:Ðspecify an object to be passed as the sender of the message.  The file finder can then send messages back to the sender while processing the query or update request.

When a file finder receives a performQuery:atPath:forSender: message, it immediately returns a list of all the files in its index that match the supplied query.  In addition, if the file finder uses an index and the index is out of date, it checks all of its out of date files in the background to see if they match the query.  If the sender of a query responds to fileFinder:didFindFile: or fileFinder:didFindFile:, then it will receive those messages for out of date files found after the query message has returned.  This guarantees that all files in the file finder's directory get checked for every query.  To stop receiving these messages after a query has begun, send the file finder a stopQueryForSender: message.

When a file finder receives an updateIndex:atPath:forSender: message, it checks whether the sender responds to fileFinder:willAddFile:.  If so, then every time a new file record would be added to the index or changed, it sends that message back to the sender of the update message.  The sender can then alter or replace the file record and return it to the file finder.  The record returned by the sender is added to the index instead of the original file record.

The sender can be specified as nil, in which case no per-file messages will be sent.  Passing nil as the sender for a query will produce incomplete results if the index is at all out of date.

Method Types

Getting the target directory	- rootPath

Getting the record manager	- recordManager

Performing queries	- performQuery:atPath:forSender:
- stopQueryForSender:

Updating indexes	- updateIndexAtPath:forSender:
- isUpdating
- suspendUpdating
- resumeUpdating
- clean
- reset

Instance Methods

clean

- clean

Removes all inaccurate or out of date information from the file finder's index, leaving the index in an incomplete, but otherwise accurate, state.  Returns self.

See also:  - reset

isUpdating

- (BOOL)isUpdating

Returns YES if the file finder is updating its index in the background.  That is, if each time it performs a query, it records those files that are out of date with respect to its index, and updates them in the background.

See also:  - suspendUpdating, - resumeUpdating, - updateIndexAtPath:forSender:, - setUpdatesAutomatically: (IXFileFinderConfiguration)

performQuery:atPath:forSender:

- (IXPostingList *)performQuery:(const char *)aQuery
atPath:(const char *)path
forSender:sender

Performs a query within the file finder's directory for all files within the subdirectory named path relative to the working directory of the process (note: previous versions of the documentation incorrectly described path as relative to the file finder's root path).   aQuery is a string defining a request in the file finder's query language (described under ªThe Indexing Kit Query Languageº in the ªOther Featuresº section of this chapter).  If there's an index, it's checked first, and results matching aQuery for all valid index entries are returned.  If there is no index, or if there are any files that are out of date with respect to the index, the file finder continues its search directly on those files in the background, sending fileFinder:didFindFile: or fileFinder:didFindList: messages to sender as it finds additional files that match aQuery.  If sender is nil or doesn't respond to fileFinder:didFindFile:, then no background searching is done.

This method returns an IXPostingList containing the immediate results of the query (the file records that were retrieved directly from the index).  It contains a set of IXFileRecords containing basic information about the files:  their names, types, modification dates, and so on.

See also:  - stopQueryForSender:, - fileFinder:didFindFile: (ªMethods Implemented by the Sender of a Query or Updateº)

recordManager

- recordManager

Returns the record manager (usually of class IXRecordManager) used by the file finder to maintain its index.

reset

- reset

Removes all information from the file finder's index, but doesn't remove the indexes themselves.  This is useful if for rebuilding a file finder's index from scratch:  to do so, send this message followed by an updateIndex:atPath:forSender: message.  Returns self.

See also:  - clean

resumeUpdating

- resumeUpdating

Resumes automatic background updating of the file finder's index after a suspendUpdating message.  If automatic updating hasn't been suspended, this method has no effect.  Returns self.

See also:  - suspendUpdating, - updateIndexAtPath:forSender:, - isUpdating, - setUpdatesAutomatically: (IXFileFinderConfiguration)

rootPath

- (const char *)rootPath

Returns the full pathname of file finder's primary directoryÐthe top level directory that the indexes are built over.  This directory is set when the file finder is initialized, and can't be changed.

stopQueryForSender:

- stopQueryForSender:sender

Stops background searching for the query last requested by  sender.  This is useful if sender doesn't want to receive any more fileFinder:didFindFile: messages after performing a query (for example, if it was looking for a specific file and found it).  This message doesn't need to be sent if the sender passed to performQuery:atPath:forSender: doesn't respond to fileFinder:didFindFile:, or if the sender was passed as nil.  Returns self.

See also:  - performQuery:atPath:usingIndexes:, - fileFinder:didFindFile: (ªMethods Implemented by the Sender of a Query or Updateº)

suspendUpdating

- suspendUpdating

Suspends automatic background updating, if it's being done.  Automatic updating may be reestablished with resumeUpdating.  Returns self.

See also:  - resumeUpdating, - updateIndexAtPath:forSender:, - isUpdating, - setUpdatesAutomatically: (IXFileFinderConfiguration), - updatesAutomatically (IXFileFinderConfiguration)

updateIndexAtPath:forSender:

- updateIndexAtPath:(const char *)path forSender:sender

Updates information in the file finder's index for all files in the subdirectory of the file finder's primary directory named path relative to the working directory of the process (note: previous versions of the documentation incorrectly described path as relative to the file finder's root path).  If  sender responds to fileFinder:willAddFile:, then during the update the file finder will send that message for every file it discovers that isn't in its index.  This operation may take some time.  Returns self.

See also:  - suspendUpdating, - resumeUpdating, - isUpdating, - fileFinder:willAddFile: (ªMethods Implemented by the Sender of a Query or Updateº)

Methods Implemented by the Sender of a Query or Update

fileFinder:didFindFile:

- fileFinder:(IXFileFinder *)aFinder didFindFile:(IXFileRecord *)aRecord

Sent during a background search by the file finder to the sender of a performQuery:atPath:forSender: message when it finds a file matching the sender's query.  Returns self.

aRecord can be used to access information about the file that matched the query, which can be displayed to the user or processed.

See also:  - performQuery:atPath:forSender:, - fileFinder:didFindList:

fileFinder:didFindList:

- fileFinder:(IXFileFinder *)aFinder didFindList:(IXPostingList *)aList

Sent during a background search by the file finder to the sender of a performQuery:atPath:forSender: message when it finds a set of files matching the sender's query.  Returns self.

aList contains IXFileRecord objects, which can be used to access information about the files that matched the query, which can be displayed to the user or processed.

See also:  - performQuery:atPath:forSender:, - fileFinder:didFindFile:

fileFinder:willAddFile:

- fileFinder:(IXFileFinder *)aFinder willAddFile:(IXFileRecord *)aRecord

Sent by the file finder to the sender of an updateIndexAtPath:forSender: message before it adds aRecord to its indexes.  The file finder will add the record returned by this method (which should be an IXFileRecord or subclass).  The receiver may alter, replace, or even free aRecord, and return the record as the receiver wants it added, or nil if the receiver doesn't want it added.  If it turns out that no changes need to be made, your implementation of this method should simply return aRecord.

See also:  - updateIndexAtPath:forSender: